DPE 数字样机编辑器（Web3D版 V7.9.66）
用户操作手册

🎬 完整制作视频教程（真实模型实操 · 约 2 分半 · 带语音解说）

使用「码垛机器人」glTF 模型（含骨骼动画）完整演示一个课件的制作流程，每一步带语音解说与字幕：

1. 启动编辑器：界面分区总览（大纲/材质/灯光/历史 · 逻辑面板 · 流程图/序列）
2. 导入 glTF 模型：层级、命名、骨骼动画完整保留
3. 大纲视图：层级展开收起、点选、Ctrl/Shift 多选、Ctrl+A 全选
4. 批量生成拆卸步骤：方向/距离/工具/提示一次成型
5. 材质工作站：80+ 种 PBR 预设一键赋予
6. 材质吸管：吸取模型自带材质，参数与贴图进入面板再编辑
7. 灯光工作站：添加聚光灯，物理阴影 + SSAO 真实感渲染
8. 爆炸图认知模式：全构件炸开并标注名称
9. 序列编辑器：骨骼动画剪辑入轨，关键帧拖动编辑
10. 一键发布：导出 .vtpack 项目文件，学员端浏览器直接播放

1. 🚀 快速上手：5 分钟做出第一个课件

1.1 快速上手路线图（新用户 5 分钟）

五步走完一条最短路径，先跑通全流程再研究细节：

1.2 五分钟实操演示

本节带您从零完成一个「拆卸演示课件」。假设您已拿到建模团队交付的 glTF 模型文件。

1. 导入模型：打开编辑器（index.html），点击顶部工具栏的「⬇ 导入模型」，选择 .gltf / .glb 文件。模型先进入底部「🗂 资源」面板的资源库，双击资源（或点「置入场景」）即放入视口，左侧「🌲 大纲」面板出现完整层级树。
2. 框选构件：在视口中按住鼠标左键拖出一个选框，框住要拆装的构件（例如 4 颗螺栓）；或在大纲面板中按住 Ctrl 逐个点击多选。被选中的构件会高亮显示。
3. 批量生成步骤：在右侧「步骤」面板点击「⚡ 批量生成步骤」，编辑器会为每个选中构件自动生成一个拆卸步骤（含位移动画方向建议），并出现在步骤列表中。
4. 演示预览：点击底部「⚡ 流程图」上的 ▶ 播放按钮，从头到尾预览整个拆装流程，检查顺序和方向是否合理；不合适的步骤可直接拖拽调整次序。
5. 发布：点击顶部工具栏「🚀 发布课件」，默认导出 .vtpack 项目文件（模型、课件逻辑、材质、步骤一体化）。用播放器（player.html）打开该文件，即可分享给学员观看。

2. 🖥 界面总览

编辑器界面分为五个区域，如下图所示（文字示意）：

3. 📦 模型导入规范（给建模团队的交付要求）

课件质量很大程度取决于模型质量。请将本页要求直接转达给建模团队。

3.1 交付格式

• 首选 glTF / GLB（.gltf / .glb），Web 端加载快、材质与动画保留完整。
• 工业模型支持 STEP / STP：主流工业软件导出的装配体可在「⬇ 导入模型」中直接选择（beta），浏览器端自动三角化转为 GLB 入资源库（精度/单位/合并模式可设，见 6.1 节）。
• 另支持 FBX / OBJ（可配 MTL 与贴图多选）/ STL / PLY，以及 PNG / JPG / WebP 贴图。
• 支持层级完整保留：建模软件中的组/父子关系会原样进入大纲树。
• 支持骨骼动画与变形动画（Morph Target），导入后可在「🎬 序列」编辑器中加载为动画轨道（见第 16 章）。

3.2 建模与命名要求

4. 🌳 大纲视图

大纲以层级树展示模型全部构件，是选择和组织构件的主要工具。

4.1 基本操作

4.2 对象分组管理（标签 / 灯光 / 相机）

v6.5 起，大纲中的标签、灯光、相机三类对象各有独立的父级根节点组（如「🏷 标签」「💡 灯光」「📷 相机」），创建的同类对象自动归入对应组下，层级清晰、便于统一管理。

4.3 大纲顶部工具条

大纲树上方有一排小按钮：📦 打组（勾选构件打成一组）、🗂 解组、👁 全部显示（一键找回被隐藏构件）、🙈 全部隐藏、☑ 全选（Ctrl+A）、🗑 删除勾选构件、📤 导出部件清单 Excel（可编辑后重新导入生成拆装步骤，见 13.4 节）。

5. 🏷 标签系统（吸附标注 · v6.5 新增）

标签是吸附在三维构件上的名称标注，带一条引导线连接标签与构件，构件移动/炸开时标签自动跟随。常用于给关键零件标注名称、编号、检修要点。

创建标签

标签属性编辑

点击场景中的标签（或大纲里点标签名）选中后，右侧属性面板可改：文字内容（多行）、文字颜色、字号、背景颜色/不透明度、边框颜色、整体透明度，以及引导线的开关、样式（直线/曲线）、颜色、粗细。

绑定管理

• 绑定模型列表：属性面板列出该标签绑定的所有模型（📌主锚点 / 🔗附加），每行可 ✕ 单独移除。
• ➕ 增加绑定：点此按钮后去三维场景点击要加入的构件（可连点多个，Esc 完成）。
• 🗑 清空绑定：一键移除所有绑定，标签变自由标签。
• 🔗 换绑目标 / ✂ 解绑：换绑=把锚点移到另一个构件；解绑=标签脱离构件不再跟随。

其他要点

• 标签位置可用变换手柄直接拖动，移动可用 Ctrl+Z 撤销；创建标签也可撤销。
• 删除某个构件时，绑定它的标签连线会一并删除（主锚点被删则自动改用附加锚点，或转自由标签）。
• 标签可在大纲打组（多选后 Ctrl+G）、批量勾选后统一改颜色/字号/连线等参数。
• 标签随工程包（.vtpack）保存与恢复。

6. 📦 资源管理面板

导入的模型先进入资源库，不直接进场景。资源库就像您的"零件货架"：先备货，再按需取用，同一个资源可重复置入多个实例。资源面板在底部页签「🗂 资源」中打开（左侧展开），每个资源卡片带实景缩略图（模型入库时自动生成 128×128 截图，旧资产打开面板自动补生成）与文件大小/构件数信息。

6.1 导入与置入（「⬇ 导入模型」统一入口）

v7.2 起「⬇ 导入模型」是唯一导入入口：点击后先弹出格式清单弹窗（三维模型 / 工业模型 / 贴图 / 工程文件四分组卡片，支持把文件直接拖拽到弹窗导入），再选择文件。

1. 导入：顶部工具栏「⬇ 导入模型」→ 选择 .gltf / .glb 等模型文件（可连同 .mtl 与贴图一起多选），模型出现在「🗂 资源」面板的资源列表中。
2. STEP / STP 工业模型：文件选择器中直接选 STEP 文件（带 beta 徽标），系统先弹参数确认面板——精度（高/中/低/自定义）、源文件单位（mm/cm/m/inch）、构件合并模式、构件数上限——确认后才开始转换，取消可放弃；转换完成自动入资源库。
3. 置入场景：双击资源条目、点「置入」按钮，或直接把资源拖入三维视口，模型即放入场景并出现在大纲树中。
4. 重复取用：同一资源可多次置入（如多颗相同的螺栓），每次置入都是独立构件，可分别编排步骤。

6.2 资源库整理

7. 🎮 视口操作

7.1 轨道相机

7.1A 🎥 相机漫游模式（顶部工具栏「相机」下拉）

7.1B 🎥 默认相机（场景主相机）

切换漫游模式时（或进入编辑器后），大纲视图顶部会出现一个置顶显示的「🎥 默认相机」节点（带「默认」徽标）——它就是当前场景的主相机：

• 置顶 + 不可删除：永远排在大纲第一行，无删除/重命名/冻结按钮，批量删除与全选均自动排除——主相机常驻，防止误删导致视角丢失；
• 视口不可见·不可聚焦自身：默认相机是观察者本身（逻辑管理节点而非场景实体）——三维视口中看不到任何代理形状，不参与鼠标拾取与框选；按 F 聚焦会提示「默认相机是观察者本身，不可聚焦自身」，视角不会突跳；
• 点击选中后，右侧属性面板显示完整相机属性：

  分组	可调参数
  📷 相机属性	视角 FOV（20°–120°，实时显示 35mm 等效焦距）· 位置 X/Y/Z · 朝向（水平角/俯仰角）· 近裁剪面 / 远裁剪面
  🚶 漫游参数	移动速度 · 鼠标灵敏度 · Shift 加速倍率（1–8×）· 曝光 · 色温（2000K–10000K 白平衡实时预览）· 碰撞检测开关（第一人称）

• 节点名称随模式自动同步（如「默认相机 [第一人称·碰撞]」）；
• API 同步开放：camera.setNavParam（位姿/裁剪面/色温/加速倍率全参数）与 camera.getPose（查询位姿/FOV/等效焦距），AI 与 iframe 宿主可完全接管相机；
• ↩ 重置（全部 + 逐参数）：面板右上「重置参数」按钮（或 API camera.resetNav）一键全部恢复——相机属性（FOV/裁剪面）恢复启动初始值、视角平滑飞回初始机位，漫游参数恢复出厂；每个参数行尾另有独立 ↩ 小按钮（或 API camera.resetParam {key}）单项重置——只恢复该参数，其它参数不动（如只调坏了 FOV 就只重置 FOV）。

7.2 变换手柄与选择

7.3 视口多选与批量赋材质（v7.3）

在视口按 Shift（Mac 为 Cmd）+ 拖框可多选构件，多选集合与大纲勾选互通。多选后：

• 在底部「🎨 材质」工作站点材质球或调通道参数，批量应用到全部勾选构件（如把 20 颗螺栓一次全设为不锈钢）；
• 点任意单个构件进入单选，但保留多选集合可继续批量调参；Esc 清空多选。

7.4 轴心点设置

遇到构件轴心不在正确位置（手柄偏移、旋转绕错点）时，选中构件在右侧「属性」面板找到「轴心点」：

1. 在下拉中选择目标位置：包围盒中心 / 底面中心 / 顶面中心 / X·Y·Z 最小·最大边线 / 最低顶点 / 最高顶点（共 11 种）；
2. 点「设置轴心」生效——勾选多个构件时批量生效；嵌套在多层组内或父级带旋转/缩放的物体设置轴心也不会飞走（v7.4 矩阵补偿，子级世界变换严格不变）；
3. 位置/旋转/缩放每行输入框旁有 ⟲ 重置按钮，可单独恢复初始值。

7.5 认知辅助模式

7.6 ✂ 剖切工具（精确断面封面）

视口工具栏「✂」打开剖切面板，选择平面剖切或体剖切（盒）后，场景中出现剖切可视化 + 橙色手柄并自动激活变换控制：

7.7 📏 测量工具

视口工具栏「📏」打开测量面板，支持四类测量：

• 距离：两点间距离；高度：垂直高度差；角度：三点夹角；面积：多边形面积。
• 智能吸附（悬停显示吸附点）：顶点 / 边中点 / 面中心，可分别开关。
• 「↩ 撤销上一点」退一个点，「🗑 清除全部」清空测量线。测量在编辑模式下可用。

7.8 渲染模式切换

视口工具栏的渲染模式下拉可切换模型显示方式：🎨 真实渲染（PBR 默认）/ ☀ 无光照 / 🔮 MatCap / 🌈 法线 / 🕸 线框——检查模型布线、法线朝向或做风格化展示时常用。另有 💡 辅助物体显隐开关：一键隐藏灯光/相机等非实体辅助物（仅影响视口显示，不影响功能；预览/播放模式自动隐藏）。

8. 🧭 属性面板（Inspector）

右侧第一个「属性」页签：选中任何对象，此处显示并可编辑它的全部关键属性。

• 构件：名称、位置 / 旋转 / 缩放（9 项数值）、轴心点下拉与「设置轴心」（见 7.4 节）、🎯 聚焦、📄 复制、📚 批量复制、🗑 删除。
• 数值拖动：位置/旋转/缩放带 X Y Z 彩色标签，按住标签左右拖动即可调值（专业三维软件拖拽调值交互）；每行 ⟲ 按钮重置初始值。
• 材质实时同步（v7.3）：材质工作站赋的材质/参数立即显示到属性面板（免材质吸管）；API/脚本改材质也会自动落盘（保存工程不丢）。
• 灯光：名称、位置、颜色、强度、投射阴影、阴影质量/偏移、色温（2000K–10000K）、「🎚 手柄移动」直接拖三轴手柄调灯位。
• 相机：FOV 视场角与焦距（35mm 等效）联动、对焦距离、光圈 f 值、曝光补偿、景深 DOF、「从此相机预览」。

9. 🎨 材质系统

9.1 PBR 通道详解

编辑器采用 PBR（基于物理的渲染）材质。选中构件后，在底部「🎨 材质」工作站可调整以下通道，每个通道都带贴图插槽，可导入外部图片替换贴图：

9.2 预设材质库（82 种 · 10 大分类）

材质工作站在底部页签「🎨 材质」（左侧展开），三栏结构：分类导航 + 材质球 + 通道编辑器。

双击预设即可赋予当前选中的构件。

9.3 常用操作

• 💉 材质吸管：点击吸管工具，再点视口中任意构件，即可吸取导入模型自带的材质参数，应用到当前选中构件。
• 批量赋予：在大纲或视口多选构件后双击预设，一次全部应用（如把所有螺栓统一设为不锈钢）；材质预设与通道参数均支持批量（见 7.3 节）。
• 恢复原始材质：点击「↩ 恢复原始材质」，回到模型导入时自带的材质状态。

10. 💡 灯光系统

10.1 三种光源

• 创建：左侧「🌌 场景」页签（或「＋ 创建」页签）点击「＋平行光 / ＋点光源 / ＋聚光灯」。
• 调整：选中灯后可直接用变换手柄拖动灯位（面板「🎚 手柄移动」；平行光调方向、聚光灯调朝向），并在面板或属性面板中设置名称、颜色、强度、阴影等参数。
• 删除：选中灯光后点击「🗑 删除灯光」或按 Delete；大纲「💡 灯光」组中也可行内 ✕ 删除、✎ 重命名、👁 显隐。

10.2 阴影与环境

10.3 真实感渲染建议组合

11. ☀ 天空组件与天气系统

左侧「🌌 场景」页签中「天空与天气（全局光照）」区。

• 天空组件：开启后为物理大气天空，全局光照（GI）由天空实时烘焙，金属/PBR 材质质感立刻提升。
• 时刻与方位：拖动「时刻」与「太阳方位」滑条即可改变日照角度。
• 天气系统：晴天 / 多云 / 阴天 / 雨天 / 雪天——联动大气雾（指数雾）、体积云层、光照强度；雨天/雪天自动生成对应天气粒子效果。

12. 🎛 渲染与性能设置（自适应画质 Governor）

「🌌 场景」页签中提供画质档位三档与自适应画质 Governor：

• 自适应画质 Governor（v7.4 起）：帧率持续偏低时自动降档（流畅模式），恢复后自动升档回原档位；v7.5 升级为「档位 × 分辨率」阶梯——降档后仍低帧则继续降低渲染分辨率、必要时紧急关闭 SMAA 自救，升档防振荡。
• 手动选画质 = 关闭自动：点了「极致 / 均衡 / 流畅」任意按钮后 Governor 自动退出，恢复满分辨率，档位完全由您掌控。
• 视口左下角实时显示帧率与构件/三角面统计；统计口径与资源库一致（叶子构件口径）。

13. 📋 步骤与流程

13.1 添加步骤

🎬 步骤制作模式：步骤面板点「🎬 步骤制作模式」→ 点选构件 → 拖三重轴臂杆 → 松手自动成步，构件自动回装配位继续下一件。拖动实时显示方向+距离；Alt+点击面=按面法线定向（斜向拆装）；Shift=自由方向；Esc 退出。重拖已有步骤的构件=更新方向距离（不重复建步）。开「附加到上一步」= 与上一步同组并行动作。

🔗 链式均分间距：同方向连续步骤一键按"前件半尺寸+本件半尺寸+基础间距"重排距离，自动防重叠。

步骤卡片：可拖拽排序、▶单步回放、⧉复制参数给选中构件、↑↓微调、✕删除；面板提供「↺ 重置（清空+归位）」「🗑 清空步骤」；有步骤后爆炸图自动=步骤终态投影（改步骤即改爆炸，数据同源）。

步骤细节手风琴（v7.3）：点击步骤卡片，其细节编辑面板紧随卡片下方手风琴展开（展开动画+自动滚动到可视区），不再翻到列表底部找；再点已展开卡片即收起。

1. 选中构件（大纲勾选或视口框选）；
2. 在右侧「步骤」面板点击「＋ 添加拆卸步骤（当前选中构件）」，为该构件生成一个拆装步骤（记录位移方向、距离、时长）；
3. 或使用「⚡ 批量生成步骤」，为多选构件一次性生成全部步骤。

13.2 并行组号

每个步骤有一个并行组号：组号相同的步骤不分先后、同时执行。典型场景：松开一个法兰上的 6 颗螺栓——它们没有严格先后关系，全部设为同一组号，播放时同步旋出，更接近真实操作。

13.3 智能排序与流程图联动

13.4 Excel 双向闭环

• 📤 导出：大纲工具条「📤」导出部件清单 Excel（名称/ID/层级路径/拆卸顺序/工具/材质/提示，已配置步骤自动回填）；无步骤时可导出清单模板盲填。
• 📥 导入：步骤面板「📥 导入拆装列表 (Excel)」支持 xlsx/csv，按 ID→名称→模糊三级匹配；中文方向（上下左右前后）与动作（拆卸/装配/检查/润滑）直接可填，全字段无损往返（含机位）。
• 导入后显示汇总（新建/更新/跳过/失败），大批量构件零手动点选。

14. 🧩 五个逻辑面板怎么配

右侧逻辑面板的五个标签页，分别控制课件播放时的五类行为。全部配置会随工程保存、随课件包发布。

14.1 🧭 引导

• 为每一步骤配置引导文字（播放时显示的操作说明，如"先松开 4 颗 M8 螺栓"）。
• 可添加高亮箭头 / 圈选指向当前操作构件，引导学员视线。
• 支持设置"必须看完引导才可下一步"等播放约束。

14.2 🎥 相机

• 为关键步骤记录相机机位：在视口摆好视角后点击「记录当前视角」，播放到该步骤时镜头自动飞过去。
• 可设飞行时长与缓动；未记录的步骤沿用上一机位。
• 建议：总览 → 局部特写 → 操作细节，形成"远景-近景"叙事节奏。

14.3 🖼 界面

• 配置播放器端界面元素：课件标题、LOGO、步骤栏样式、是否显示进度条与目录。
• 可上传封面图与背景色，形成企业统一的课件风格。

14.4 🔧 工具

• 为步骤关联工具：如"扭矩扳手""一字螺丝刀"，播放时在工具区同步展示。
• 维护本项目常用工具清单（名称 + 图标），供各步骤下拉选用。

14.5 📝 考核

• 把指定步骤标记为考核点：学员需在播放器中点选正确构件才算通过。
• 可设置每题分值、是否允许多次尝试、答错提示语。
• 考核结果在播放结束时汇总显示得分（判错逻辑见 FAQ 第 5 条）。

15. 🕘 历史记录

• 所有操作可回溯：移动构件、改材质、删节点、改步骤……每一次编辑都会记录在左侧「历史」面板中。
• 点击回到任意一步：历史列表按时间倒序排列，点击任意记录，场景直接回滚到该时刻状态，其后操作保留在列表中（再做新操作才会截断）。
• 快捷键：Ctrl+Z 撤销，Ctrl+Y 重做。
• 清空：面板底部「清空历史」释放内存；清空后不可恢复，工程量大时建议定期清空以保持流畅。

16. 🎬 序列编辑器（专业级动画系统）

底栏「🎬 序列」页签是 v7.1 起的动画制作中心（取代旧版「动画时间轴」，旧称「动画编辑器」已并入本系统）。心智模型对齐专业级序列编辑器：序列（Sequence）→ 物体绑定（Binding）→ 属性行（Track）→ 关键帧（Key），支持多序列、全属性 K 帧、模型自带动画轨道、片段裁剪与倒放。

16.1 界面布局

┌ 工具条：▶/⏸ ⏹ ⏮ ⏭ ⏪（倒放）｜ 时间 时长 帧率｜循环（➊不循环/🔁循环/⇄往返）｜速率 优先级 吸附｜渲染视频 ┐
├ ② 序列列表（180px，可拖宽）┬ ③ 轨道树（250px，可拖宽）┬ ④ 时间线（刻度+播放头+关键帧方块+动画片段块） ┤

• 序列列表：搜索过滤；每行 = 启用开关 / 名称 / 时长 / ✏ 重命名 / ⧉ 复制 / ✕ 删除；单击切换当前编辑序列。
• 轨道树（三级折叠，默认收起）：物体行 → L1 组（🧭 变换 / 🎨 材质 / 💡 灯光 / 📷 相机 / 🏷 标签 / 👁 杂项）→ L2 子组 → L3 叶子属性行（当前值输入框 + ◆ 打帧按钮 + 🗑 删轨道）；展开状态有记忆。
• 时间线：拖顶部刻度条 = 播放头 scrub 实时预览；红色竖线 = 时长右边界；空格 播放/暂停。

16.2 加入物体与全属性 K 帧

1. 新建序列：序列列表「＋」新建（可命名、设时长与帧率）；
2. 加入物体：从左侧大纲把构件 / 相机行直接拖到序列行或轨道树（支持勾选多选后整组拖入）；
3. 打关键帧：展开属性树，把播放头拖到目标时间，在属性行输入框改值 = 自动在该时刻打帧（有轨道时"沿轨道调整即 K 帧"）；也可点 ◆ 按当前值打帧；
4. 插值：auto（Catmull-Rom 平滑）/ linear / constant（阶梯）/ easeIn / easeOut / ease 六种；
5. 可 K 帧属性白名单：构件（变换各轴/可见性/材质颜色·金属度·粗糙度·发光·透明度）、灯光（强度/颜色/显隐）、相机（FOV/对焦/光圈/曝光）、标签（文字/显隐/颜色）。

16.3 关键帧编辑

• 选择：单击单选、Ctrl+点击加选、空白拖动框选（跨属性行）、Esc 取消；
• 移动：拖动关键帧改时间（吸附帧网格）；拖动任一选中帧整体移动（显示 Δt 提示）；Alt+拖动复制；
• 右键菜单：设值 / 设时间 / 六种插值 / 复制到播放头 / 删除所选；Delete 删全部选中；
• 时间缩放：Ctrl+滚轮（以指针为锚）；父行显示子关键帧汇总刻线。

16.4 模型自带动画轨道（骨骼/剪辑动画）

含动画的模型（glTF/FBX 骨骼蒙皮、节点动画）通过「⬇ 导入模型」导入后，从大纲拖入序列，在「变换」组上方出现「🎬 动画」轨道行：

• 点「＋加载动画」弹出该物体可用剪辑多选列表（已加载项预勾选，取消勾选=移除）；
• 已加载剪辑在时间线上显示为动画片段块（紫色 section 条）：拖动改起始（吸附帧网格）、右键删除；
• 片段裁剪（v7.3）：拖拽片段左右端改入点/出点（可延长回原长）、播放头处剪断拆成两段（视频剪辑软件式）；时间线长度自适应扩容；
• 序列播放时剪辑由 AnimationMixer 驱动；暂停保持当前时间可继续，停止/禁用/解绑级联停止。

16.5 多序列、优先级与循环

• 多序列：可建任意多个序列，同时启用、独立播放（▶ 也可指定播放非激活序列）；
• 优先级：同一属性被多个启用序列驱动时，优先级大者胜，相等则数值/颜色线性混合；
• 禁用恢复基线：禁用序列自动把属性写回基线值，与数据绑定、脚本驱动三方共存（详见 20.2.8 冲突说明）；
• 循环：不循环 / 循环 / 往返三态；速率 0.25×~4×；⏪ 倒放（t=0 时从末尾开始，倒完自动停）。

16.6 序列标记物

把序列列表行拖进三维视口，在落点创建 🎬 标记物（序列自动启用）：

• 标记物显示在大纲「🎬 序列」分组（行 = 名称 + 👁 开关 + ✕ 删除），视口中可点选、可沿水平面拖动；
• 选中标记物后属性面板显示序列属性（名称/启用/优先级/时长/循环/速率/影响物体数）与完整播放控制（播放⇄暂停状态互切、停止、倒放）；
• 「启用」是唯一求值开关：列表勾选框 / 大纲眼睛 / 属性面板开关三方实时同步。

16.7 渲染视频

工具条「渲染视频」：弹窗设置分辨率（当前视口/720p/1080p/2K）、帧率（24/30/60）、码率（8/16/28Mbps）、格式（mp4/webm）→ 从 0 秒播放当前（或选中标记的）启用序列并录制三维视口 → 完成后自动下载 DPE_序列渲染_*.mp4/webm，浮动进度条可取消。无启用含帧序列时会提示先制作动画。

16.8 旧数据迁移（旧「动画时间轴」）

旧版底栏「动画时间轴」页签已移除，功能全部由序列编辑器接管：

• 旧工程的时间轴数据：旧 state.timeline 关键帧在工程中只读保留，可通过 sequencer.importLegacy 能力一键迁移并入序列「导入的旧动画」（迁移规则：旧 pos/rot/scale 拆为变换三轨、颜色→材质色、灯光强度/相机 FOV 等按白名单映射）；v7.3 起面板不再提供「导入旧时间轴」按钮，能力保留供脚本/存档流程调用；
• 含动画的模型：统一走顶部「⬇ 导入模型」入口（序列面板的「导入动画模型」按钮已移除），导入后从大纲拖入序列即见动画轨道；
• 典型用法不变：先让机械臂动画播放到指定姿态，再衔接拆卸步骤——用片段块的起始时间对齐即可。

17. 💾 保存 / 另存为 / 打开

18. 🚀 发布与播放器

点击顶部「🚀 发布课件」弹出发布面板，四种发布形态：

1. 📦 项目文件（.vtpack）★推荐（主形态）：模型 + 课件逻辑 + 材质 + 步骤一体化的项目工程文件；用播放器（player.html）打开即自动进入课件播放模式，免安装、可离线分发。
2. ☁ 在线分享链接：工程文件存入云端工程库后生成直开链接，学员点开链接即播放在线加载课件（云端工程库服务接入后生效，当前先提供本地部署播放器链接）。
3. 🎬 录制培训视频：自动进入演示模式完整播放拆装流程，同时录制三维视口为视频文件（webm/mp4）保存到本地。
4. 🔗 集成导出（嵌入第三方系统·兼容）：导出兼容课件包（glb + json）并生成 iframe 嵌入代码；播放器支持 URL 参数直读，可嵌入任意系统页面（进度条真实推进至 100%）。

播放器（player.html）

• 纯净播放器：无品牌字样（标题随课件名），播放什么课件完全由您加载的项目决定；主入口为「📦 打开项目文件（.vtpack，兼容旧 json + glb 分离格式，自动识别）」。
• 三种学习模式：演示学习 / 培训练习 / 考核；进入模式后不自动开始，显示「开始播放 / 开始练习 / 开始考核」大按钮，点击才启动（考核点开始才计时）；模式中可随时打开其他课件。
• 播放器材质继承：编辑器中赋的材质（颜色/金属度/粗糙度/发光/贴图）随工程包带入播放器；五格式模型通吃，编辑器改色→保存→播放器逐项一致。
• 只读环境：学员只能观看流程、参与考核，不能改动课件内容，放心分发。学员无需安装任何软件，浏览器点开即学。

19. 🔌 DPE API：UI 图表编辑器 ↔ Web3D 编辑器联动

版本 v1.0.0 · 适用：任意 Web 系统通过 iframe 嵌入 DPE 数字样机编辑器 · 无依赖，Vue / React / 原生 JS 通用

cimpro3d-api.js 是挂在 window.CIMPro3D 上的 UMD 模块，为父页面提供对象、材质、相机、灯光、动画、天气、GIS 图层、数据驱动创建等八类场景控制能力。父子页面跨域时走 postMessage 双向桥（Promise 化），同源时也可直接调用。

19.1 集成方式

① 编辑器侧（子页面，一行接入）

<!-- 主文件尾部，module 脚本之后 -->
<script src="cimpro3d-api.js"></script>

模块内部经 window.__scene / window.__state / window.__dbg 钩子访问编辑器（主文件已内置）；缺省自动降级为 DOM 控件 / 纯场景操作。补充可选钩子 window.__hooks 后能力完整（见 X.7）。

② 父页面侧（UI 图表编辑器）

<iframe id="editor3d" src="https://your-host/index.html"
        style="width:100%;height:640px;border:0;"></iframe>
<script src="cimpro3d-api.js"></script>
<script>
  const bridge = CIMPro3D.createBridge(document.querySelector('#editor3d'));
  await bridge.ready;                       // ready 握手
  await bridge.call('setWeather', '雨天');   // Promise 化调用
  bridge.on('select', ({id, name}) => console.log('三维中选中：', name));
</script>

19.2 API 方法总表

基础与事件

对象控制

材质

相机

灯光

动画

天气 / 环境

图层 / GIS · 数据驱动

19.3 postMessage 消息协议

命名空间 ns:'cimpro3d'，三种帧：

// 父 → 子：命令
{ ns:'cimpro3d', type:'cmd', id:'m1', method:'setWeather', args:['雨天'] }

// 子 → 父：响应（ok/result 或 ok:false/error）
{ ns:'cimpro3d', type:'res', id:'m1', ok:true, result:true }
{ ns:'cimpro3d', type:'res', id:'m1', ok:false, error:'未找到对象：转轮' }

// 子 → 父：事件广播
{ ns:'cimpro3d', type:'event', event:'select', data:{ id:'p3', name:'转轮' } }

19.4 Vue 3 用法

<template>
  <iframe ref="frame" src="/editor/index.html" />
</template>
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import 'cimpro3d-api.js';            // 或 public 目录 script 标签引入
const frame = ref(null);
let bridge, offSelect;
onMounted(async () => {
  bridge = window.CIMPro3D.createBridge(frame.value);
  await bridge.ready;
  offSelect = bridge.on('select', ({ name }) => console.log(name));
  await bridge.call('focus', '转轮');
});
onBeforeUnmount(() => { offSelect?.(); bridge?.destroy(); });
</script>

19.5 React 用法

import { useEffect, useRef } from 'react';
import 'cimpro3d-api.js';

export default function Editor3D() {
  const ref = useRef(null);
  useEffect(() => {
    const bridge = window.CIMPro3D.createBridge(ref.current);
    const off = bridge.on('select', ({ name }) => console.log(name));
    bridge.ready.then(() => bridge.call('setWeather', '多云'));
    return () => { off(); bridge.destroy(); };
  }, []);
  return <iframe ref={ref} src="/editor/index.html"
                 style={{ width: '100%', height: 640, border: 0 }} />;
}

19.6 典型场景：图表联动三维

// ECharts 饼图点击 → 三维高亮 + 聚焦
chart.on('click', async (p) => {
  await bridge.call('clearHighlight');
  await bridge.call('highlight', p.name, '#f5a524');
  await bridge.call('focus', p.name, 1.0);
});
// 实时数据 → 数据驱动标牌
await bridge.call('clearDataObjects');
await bridge.call('createFromData', sensors.map(s => ({
  type: 'sphere', name: s.id, pos: [s.x, s.y, s.z],
  radius: 0.3, color: s.alarm ? '#e5484d' : '#34c98e', data: s
})));

19.7 可选增强钩子与降级行为

主文件尾部追加一行即可获得完整能力（缺省时按下表降级）：

window.__hooks = { THREE, renderer, camera, controls, flyCamera,
  addLight, removeLight, renderLightList, highlightPart, clearHighlights,
  regNode, renderAll, WEATHERS, updateSky, gisClear, tlSetTime,
  load3DTiles: load3DTilesReal,
  tlPlay:  () => $('#tlPlay').click(),
  tlPause: () => $('#tlPause').click(),
  tlStop:  () => $('#tlStopAll').click() };

🛰 数据驱动（数字孪生）

外部系统通过 dataPush 实时驱动场景任意对象；变换自动走平滑插值补间（默认 1.2 秒），数据稀疏（如每分钟一次）也能连续运动；驱动根构件自动带动整个层级（如坦克整车）。

// 物联网平台每 60s 推送坦克经纬度 → 平滑行驶
setInterval(async ()=>{
  const d = await fetch('/api/tank').then(r=>r.json());
  bridge.call('dataPush', '坦克', { lonlat:[d.lon, d.lat, d.alt] }, { smooth:60 });
}, 60000);
// 设备报警 → 变红闪烁
bridge.call('dataAlert', '泵机A', '#ff2200', 8);

20. 📜 脚本系统与数据驱动实战

v7.0 起提供两套互补的「让场景动起来」的机制：脚本系统（左侧「📜 脚本」页签，游戏引擎组件式心智模型）与数据驱动（左侧「📡 数据」页签，数字孪生数据绑定引擎）。本章从入门讲到实例，最后给出四层协作的综合实战。

20.1 脚本系统（左侧「📜 脚本」页签）

20.1.1 入门：什么是脚本驱动

脚本系统采用 游戏引擎组件式心智模型：一个脚本 = 一段挂在某个构件上的小程序，引擎按帧调度它，你在四个生命周期钩子里写逻辑（初始化 / 每帧更新 / 响应事件 / 销毁清理），通过 ctx 上下文读写场景属性——不需要接触底层三维 API，也不需要操作 DOM。

• 脚本模型：{name, target:'构件名|*', code, enabled}。宿主（target）是脚本默认操作的构件；ctx.get/set 直接作用于宿主，操作其他构件用 ctx.find('名称')。
• 调度：全部脚本共享一个 requestAnimationFrame 循环，dt 为帧间隔秒数（钳制 0~0.1，切后台回来不会跳变）。
• 安全：软沙箱编译——window / document / fetch / WebSocket / setTimeout 等全局被屏蔽为 undefined，脚本只能通过 ctx 触碰场景。

20.1.2 面板入口与创建流程

1. 点击左侧页签栏「📜 脚本」打开脚本面板（顶部有 ▶ 运行引擎 / 暂停 / 单步 按钮）。
2. 顶部下拉选择模板，点「＋从模板新建」（7 个开箱模板），或点「＋空白」从零编写。
3. 确认宿主构件：默认取当前选中构件，无选中时取场景第一个构件，也可手填其他构件名或 *。
4. 在代码编辑器中修改代码，点「💾 保存并重编译」。
5. 打开脚本行的启用开关即生效——引擎未运行时会自动启动，不必手动点「运行引擎」。

20.1.3 生命周期 API

代码中直接声明以下函数即可（也支持顶层 return {onInit, onUpdate, ...} 的写法），运行在严格模式软沙箱中：

20.1.4 ctx 上下文 API 参考

ctx 是脚本与场景的唯一触点（对象已冻结，不可篡改）：

20.1.5 属性路径速查表

所有驱动方式（GUI / 数据绑定 / 脚本 / API）共用同一套属性路径，完整清单如下：

20.1.6 脚本实例（7 例）

// 每帧绕 Y 轴旋转 5°（官方验收用例）
function onUpdate(ctx, dt){
  const step = ctx.math.deg2rad(5) * dt;
  ctx.set('transform.rotation.y', ctx.get('transform.rotation.y') + step);
}

// 正弦上下浮动
var y0 = 0, AMP = 0.5, FREQ = 0.5; // 振幅(米) / 频率(Hz)
function onInit(ctx){ y0 = ctx.get('transform.position.y'); }
function onUpdate(ctx){
  ctx.set('transform.position.y', y0 + AMP * ctx.math.sin(2 * ctx.math.PI * FREQ * ctx.time.t));
}

// 呼吸灯：材质 emissiveIntensity 脉动
function onInit(ctx){ ctx.set('material.emissive', '#ff8800'); }
function onUpdate(ctx){
  const k = 0.5 + 0.5 * ctx.math.sin(2 * ctx.math.PI * 0.8 * ctx.time.t);
  ctx.set('material.emissiveIntensity', 0.2 + 1.8 * k);
}

// 跟随另一个构件（修改 FOLLOW 为目标构件名）
var FOLLOW = '主轴';
function onUpdate(ctx){
  const other = ctx.find(FOLLOW);
  if(!other){ return; }
  ctx.set('transform.position.x', other.get('transform.position.x'));
  ctx.set('transform.position.z', other.get('transform.position.z'));
}

// 点击变色：需要场景在拾取后 emit('object.clicked', {name:构件名})
var PALETTE = ['#e74c3c','#f5a524','#34c98e','#3d9dff','#a06cff'];
function onEvent(ctx, name, payload){
  if(name !== 'object.clicked'){ return; }
  const hit = payload && (payload.name || payload.target || payload.id);
  if(hit !== ctx.target){ return; }            // 只响应点到自己
  ctx.set('material.color', PALETTE[ctx.math.floor(ctx.math.random() * PALETTE.length)]);
  ctx.log('被点击，已变色');
}

// 告警闪烁：配合数据绑定规则事件（或任何 alarm 事件）
var until = -1;
function onEvent(ctx, name, payload){
  if(name === 'binding.rule.triggered' || /alarm|告警/i.test(name)){
    until = ctx.time.t + 3; // 再闪 3 秒
    ctx.log('收到告警事件:', name);
  }
}
function onUpdate(ctx){
  if(ctx.time.t < until){ ctx.set('visibility', ctx.math.sin(ctx.time.t * 20) > 0); }
  else { ctx.set('visibility', true); }
}

// 定时任务：每 10 秒自检一次（利用 ctx.time，禁用 setTimeout）
var LAST = -1;
function onInit(ctx){ ctx.log('自检脚本已启动，每 10 秒检查一次'); }
function onUpdate(ctx){
  if(ctx.time.t - LAST < 10){ return; }        // 距上次自检不足 10 秒
  LAST = ctx.time.t;
  const y = ctx.get('transform.position.y');
  ctx.log('自检通过 · 累计运行 ' + ctx.time.t.toFixed(1) + 's · 当前高度 ' + y.toFixed(2) + 'm');
}

20.1.7 编辑器功能（CodeMirror IDE 化）

20.1.8 注意事项

20.2 数据驱动（左侧「📡 数据」页签）

20.2.1 入门：什么是数据驱动

数据驱动（数字孪生）= 把外部数据源的实时字段，绑定到场景元素的属性上：数据一来，AGV 自动移动、状态灯自动变色、POI 标签自动刷新——全程零代码。点击左侧页签「📡 数据」打开数据绑定面板（两个页签：绑定 / 告警规则；顶部状态条显示引擎运行状态、绑定数、规则数、累计写入次数）。

场景属性共有四种驱动方式，全部经过同一属性层（同一套属性路径），每次写入都记录来源：

20.2.2 数据源类型

20.2.3 绑定模型：数据源 → JSON 路径 → 转换 → 目标属性

20.2.4 阈值告警规则

• when 条件：{object, path, op, value}——监视任意场景属性，op 支持 < > <= >= == !=。
• 边沿触发：条件由假变真的那一刻执行一次（锁存），条件恢复为假后自动复位、允许下次再触发——不会每个帧重复触发；面板实时显示「已触发 N 次 / 当前告警中」。
• 动作类型：①prop——设置任意对象属性（如 material.emissive='#ff2200'，归属 source:'rule'）；②event——发送自定义事件（可带 payload）。
• 统一触发事件：每条规则触发时引擎都会广播 binding.rule.triggered（含 ruleId/ruleName/value/when）——脚本模板「告警闪烁」正是消费这个事件实现声光联动（见 20.1.6 实例 6）。

20.2.5 数据驱动实例（5 例）

每个实例给出面板配置步骤与等价的 JSON（JSON 可通过能力 binding.create / rule.create 调用，或「导出」按钮从剪贴板获取同构数据）。创建绑定后面板会自动启动引擎。

{
  "name": "顶盖高度演示",
  "enabled": true,
  "source": { "type": "simulator", "mode": "sine", "freq": 0.5, "amp": 1, "offset": 0 },
  "path": "$.value",
  "transform": { "map": [-1, 1, 0.4, 2.0] },
  "target": { "object": "顶盖", "property": "transform.position.y" }
}

// 绑定：电量 → 状态灯亮度
{
  "name": "AGV-01 电量监视",
  "source": { "type": "simulator", "mode": "playback",
              "values": [95, 85, 70, 55, 40, 25, 18, 12], "intervalMs": 1000, "loop": true },
  "path": "$.value",
  "transform": { "map": [0, 100, 0.15, 2.0] },
  "target": { "object": "AGV-01状态灯", "property": "material.emissiveIntensity" }
}
// 告警规则：电量过低（20% 对应强度约 0.52）
{
  "name": "电量过低告警",
  "when": { "object": "AGV-01状态灯", "path": "material.emissiveIntensity", "op": "<=", "value": 0.51 },
  "actions": [
    { "type": "prop", "target": "AGV-01", "property": "material.color", "val": "#e5484d" },
    { "type": "event", "name": "alarm.battery", "payload": { "level": "low" } }
  ]
}

{ "name": "AGV-01 位置X", "source": { "type": "websocket", "url": "ws://127.0.0.1:9001" },
  "path": "$.agv.pose.x", "target": { "object": "AGV-01", "property": "transform.position.x" } }

{ "name": "AGV-01 位置Z", "source": { "type": "websocket", "url": "ws://127.0.0.1:9001" },
  "path": "$.agv.pose.z", "target": { "object": "AGV-01", "property": "transform.position.z" } }

{ "name": "AGV-01 朝向", "source": { "type": "websocket", "url": "ws://127.0.0.1:9001" },
  "path": "$.agv.heading", "transform": { "expr": "x * Math.PI / 180" },
  "target": { "object": "AGV-01", "property": "transform.rotation.y" } }

// 服务端推送的 JSON 消息格式（每 200ms 一条）：
// { "agv": { "id": "AGV-01", "pose": { "x": 12.4, "y": 0, "z": -3.2 },
//            "heading": 90, "speed": 1.8, "battery": 76 } }

{
  "name": "泵机A 状态灯",
  "source": { "type": "http-poll", "url": "http://127.0.0.1:9000/api/device/pump-a", "interval": 2000 },
  "path": "$.status",
  "transform": { "expr": "x > 0 ? '#e5484d' : '#34c98e'" },
  "target": { "object": "泵机A", "property": "material.color" }
}

{ "name": "AGV-01 速度标签", "source": { "type": "http-poll", "url": "http://127.0.0.1:9000/api/agv/01", "interval": 2000 },
  "path": "$.speed", "transform": { "expr": "'速度 ' + x.toFixed(1) + ' m/s'" },
  "target": { "object": "lbl_agv01", "property": "label.text" } }

{ "name": "AGV-01 电量标签", "source": { "type": "http-poll", "url": "http://127.0.0.1:9000/api/agv/01", "interval": 2000 },
  "path": "$.battery", "transform": { "expr": "'电量 ' + Math.round(x) + '%'" },
  "target": { "object": "lbl_agv01", "property": "label.text" } }

// 离线演示版（无需接口，playback 轮播字符串）：
{ "name": "电量标签（离线演示）",
  "source": { "type": "simulator", "mode": "playback",
              "values": ["电量 95%", "电量 72%", "电量 48%", "电量 25%", "电量 18%"], "intervalMs": 2000, "loop": true },
  "path": "$.value", "target": { "object": "lbl_agv01", "property": "label.text" } }

20.2.6 驱动归属面板（whoDrives）

每次属性写入都会记录来源，绑定列表每一行都显示「驱动归属： source @ 时间」——这个属性现在被谁驱动、最后一次写入是什么时候，一眼可查（来源取值：gui / binding / script / rule / api）。控制台亦可直查：

// 查询某属性当前被谁驱动（返回 { source, t } 或 null）
CIMPRO.props.whoDrives('AGV-01', 'transform.position.x')
// → { source: "binding", t: 1726636800000 }

20.2.7 piadmin 对接（漂视工作台数据源）

piadmin 适配器面向企业工作台数据源接入，优先 WebSocket 实时推送，失败自动降级为 5 秒轮询。接口常量（联调时以 piadmin.picimos.com/datasource 实际接口为准）：

接入步骤：① 工作台获取数据集 ID 与访问 token；② 用能力 datasource.test 验连通（{type:'piadmin', token, datasetId} 会返回数据集清单）；③ 新建绑定：数据源类型 piadmin，参数 {"baseUrl":"...","token":"...","datasetId":"..."}；④ 数据路径按推送 JSON 结构填（如 $.fields.temp.value）。

联调校准点：数据集列表返回结构（当前兼容 {data:[...]} / {list:[...]} / 直接数组三种形态，联调后收窄）、鉴权头形式、WebSocket 推送消息的字段结构——这三处以实际接口回包为准，适配常量集中在 modules/databind/databind.js 顶部的 PIADMIN_API。

20.2.8 注意事项

20.3 组合实战：智能工厂 AGV 监控场景（四层协作）

场景：一台 AGV 在车间巡查，位置由 MES 经 WebSocket 实时推送；电量由 playback 模拟下降；电量低于 20% 时车体变红闪烁、POI 标签告警、父页面大屏一键聚焦——数据绑定管数据、规则管阈值、脚本管行为、API 管集成，四层各司其职：

第 ①② 层：绑定与规则（可整包导入，或「导出」按钮生成同构 JSON）

{
  "version": 1,
  "kind": "cimpro.databind",
  "bindings": [
    { "name": "AGV-01 位置X", "source": { "type": "websocket", "url": "ws://192.168.1.60:9001" },
      "path": "$.agv.pose.x", "target": { "object": "AGV-01", "property": "transform.position.x" } },
    { "name": "AGV-01 位置Z", "source": { "type": "websocket", "url": "ws://192.168.1.60:9001" },
      "path": "$.agv.pose.z", "target": { "object": "AGV-01", "property": "transform.position.z" } },
    { "name": "AGV-01 朝向", "source": { "type": "websocket", "url": "ws://192.168.1.60:9001" },
      "path": "$.agv.heading", "transform": { "expr": "x * Math.PI / 180" },
      "target": { "object": "AGV-01", "property": "transform.rotation.y" } },
    { "name": "AGV-01 电量→状态灯", "source": { "type": "simulator", "mode": "playback",
      "values": [95, 85, 70, 55, 40, 25, 18, 12], "intervalMs": 1000, "loop": true },
      "path": "$.value", "transform": { "map": [0, 100, 0.15, 2.0] },
      "target": { "object": "AGV-01状态灯", "property": "material.emissiveIntensity" } },
    { "name": "AGV-01 电量标签", "source": { "type": "simulator", "mode": "playback",
      "values": [95, 85, 70, 55, 40, 25, 18, 12], "intervalMs": 1000, "loop": true },
      "path": "$.value", "transform": { "expr": "'电量 ' + Math.round(x) + '%'" },
      "target": { "object": "lbl_agv01", "property": "label.text" } }
  ],
  "rules": [
    { "name": "电量过低告警",
      "when": { "object": "AGV-01状态灯", "path": "material.emissiveIntensity", "op": "<=", "value": 0.51 },
      "actions": [
        { "type": "prop", "target": "AGV-01", "property": "material.color", "val": "#e5484d" },
        { "type": "event", "name": "alarm.battery", "payload": { "level": "low" } }
      ] }
  ]
}

第 ③ 层：两个脚本

脚本 A「告警闪烁」：宿主 = AGV-01，代码直接用 20.1.6 实例 6（监听 binding.rule.triggered，闪烁 3 秒）。

脚本 B「云台跟随」：宿主 = 巡检云台（实例 4 的带偏移变体，保持 2 米跟随距离）：

// 巡检云台跟随 AGV-01（保持 2 米偏移）
var TARGET = 'AGV-01';
var OFFSET_X = 2.0, OFFSET_Z = 2.0;
function onUpdate(ctx){
  const agv = ctx.find(TARGET);
  if(!agv){ return; }
  ctx.set('transform.position.x', agv.get('transform.position.x') + OFFSET_X);
  ctx.set('transform.position.z', agv.get('transform.position.z') + OFFSET_Z);
}

第 ④ 层：父页面 API 联动（孪大师 UI 图表编辑器 / 任意前端）

// 第 19 章 bridge（iframe 模式）或 v7.2 SDK（direct 模式）均可
const st = await bridge.call('getObject', 'AGV-01');   // 查询 AGV 位姿/状态
await bridge.call('focus', 'AGV-01', 1.0);             // 告警时一键飞镜头
bridge.on('select', ({ name }) => console.log('选中：', name));
// SDK direct 模式「万能驱动口」一行驱动任意属性（与绑定/脚本同源）：
sdk.setData('AGV-01', { color: alarm ? '#e5484d' : '#34c98e' });

21. ⚡ 交互系统详细教程（事件→条件→动作）

交互系统在右侧面板的「⚡ 交互」页签（位于「属性」与「步骤」之间，v7.7 起为独立面板）。它让你零代码地回答一个问题：「当某件事发生时，如果满足某个条件，就依次执行这些动作」。本章从概念讲到三个手把手实例，再到与脚本/数据/API 的联动，最后是最佳实践。

21.1 核心概念：事件 → 条件 → 动作链

一条交互规则（简称「规则」）由三段组成，就像一句话：

21.2 面板总览与卡片化规则

打开右侧「⚡ 交互」页签，面板分为四个区域：

1. 顶栏：标题 +「＋ 新建规则」按钮（打开分步向导）；
2. 当前目标行：显示当前选中的对象（如「当前目标：顶盖（构件）」），右侧有 「当前目标 / 全部规则」切换——「当前目标」只看与选中对象相关的规则（含 * 通配），「全部规则」看整个工程；
3. 规则卡片列表：每条规则一张卡片，折叠态只有两行——第一行：状态色点（绿=启用 / 灰=停用）+ 规则名 + 「动作 ×N」徽标 + 启停开关 + 展开箭头；第二行：触发摘要（目标 · 事件 · 条件）+ 试运行 ▶ + 删除 🗑；
4. 空态引导：还没有规则时显示「还没有交互规则，点击『新建规则』让场景活起来 ✨」。

21.3 分步向导：三步创建一条规则

点「＋ 新建规则」进入向导，每屏只回答一个问题，不再是一整屏表单：

21.4 手把手实例一：点击构件变告警色 + 弹提示

目标：学员单击「顶盖」，蜗壳变红并弹出提示（认知模式标红关键件）。

1. 大纲选中「顶盖」→ 右侧「⚡ 交互」→「＋ 新建规则」（触发对象已自动填「顶盖」）；
2. ① 事件源：事件类型点选「🖱 单击构件」→ 下一步；
3. ② 条件：直接「下一步」跳过；
4. ③ 动作：动作 1 选「设置属性」，目标 蜗壳、属性路径 material.color、值 #ff0000；点「＋ 添加动作」，动作 2 选「提示消息」，消息填「蜗壳为过流部件，注意检修」；
5. ④ 完成：命名「点顶盖→蜗壳变红」，创建。

切换到演示模式，点击顶盖即可看到效果。卡片上的「▶ 试运行」可在编辑态直接验证动作链。

21.5 手把手实例二：数据变化自动切相机（聚焦告警设备）

目标：某构件属性被数据/脚本改变时（如温度超标写入 material.color），相机自动聚焦它。

1. 「＋ 新建规则」→ ① 事件源：触发对象填该构件名（如 顶盖），事件选「⚙️ 属性变化」，监听属性填 material.color；
2. ② 条件：启用条件，条件对象 顶盖、属性 material.color、操作符 ==、值 #ff0000（只有变红才聚焦，变其他色不理会）；
3. ③ 动作：动作 1 选「调用能力」，能力 camera.focus，参数JSON {"target":"顶盖","duration":1.2}；动作 2 选「提示消息」「设备告警，已自动聚焦」；
4. ④ 完成：命名「告警变色→自动聚焦」，创建。

之后无论是数据绑定、脚本还是 API 把该构件改红，相机都会飞过去——属性变化事件天然贯通四层驱动（GUI / 绑定 / 脚本 / API）。

21.6 手把手实例三：hover 高亮 + 显示信息标签

目标：鼠标移入「主轴」时高亮并在标签里显示参数，移出时还原。

1. 规则 A「移入主轴→高亮+标签」：① 触发对象 主轴、事件「➡️ 鼠标移入」；② 无条件；③ 动作 1 调用能力 object.highlight，参数 {"target":"主轴","color":"#f5a524"}，动作 2 调用能力 label.popup（或设置属性控制预制标签 visible=true）；
2. 规则 B「移出主轴→还原」：事件「⬅️ 鼠标移出」，动作把标签 visible=false 并再次调用 object.highlight 取消（或设置属性还原颜色）。

21.7 与脚本 / 数据 / API 联动（interact.trigger 外部驱动）

「🔌 自定义事件」让交互规则可以被外部系统驱动：脚本的 ctx.emit、数据绑定规则、SDK/MCP/父页面 API 都能触发。

// 1) 创建一条 custom 规则（面板里事件类型选「自定义事件」，事件名 door.opened）
//    动作链：设属性 → 发事件 → 提示

// 2) 脚本驱动（脚本内任意位置）
function onInit(ctx){ ctx.emit("door.opened", { speed: 2 }); }

// 3) API 驱动（控制台 / SDK / MCP / 父页面）
await sdk.call('interact.trigger', { name: 'door.opened', payload: { speed: 2 } });
// → 匹配事件名的全部规则依次执行整条动作链，返回 { fired: N }

// 4) 规则动作里也可「发送事件」转发载荷，外部系统可订阅：
//    CIMPro3D 事件总线 on('door.anim.start', payload => ...)

21.8 API 速查（interact.* 共 9 项能力）

规则随工程保存（interactRules 节点），创建/删除可撤销重做。

21.9 最佳实践

• 命名讲清楚因果：「点顶盖→蜗壳变红」优于「交互1」；卡片折叠态靠名字快速定位；
• 动作链宜短：3 步以内最好；复杂逻辑交给脚本，用 interact.trigger 或 ctx.emit 触发一组规则；
• 条件只做开关：条件适合「状态门槛」（如原色才变色）；需要 if/else 分支时建两条互补规则（满足 A 变红 / 否则变绿）；
• 善用通配与场景级：触发对象 * 对全部构件生效（如「点任何构件→显示名称标签」）；scene 适合自定义事件入口规则；
• 调试顺序：先「▶ 试运行」验证动作链本身，再验证事件触发（演示模式点击），最后核对条件；
• 与 20 章四层协作：位置归 binding、行为逻辑归 script、用户点击响应归 interact——同一属性别让多层同时写。

22. 🧩 蓝图编排（节点式可视化逻辑）

面向：需要在更复杂逻辑下编排交互的课件作者（无需编程基础）。如果第 21 章的「事件→条件→动作」规则是表单式配置，蓝图则是节点拖拽连线式编排——适合多步骤链式动作、带分支判断、跨二维/三维/数据源联动的场景。两套系统可并存使用。

22.1 蓝图与交互系统的关系（怎么选）

22.2 打开蓝图工作区

两个入口任选：

• 顶栏按钮：点击顶部工具栏的 🧩 蓝图 按钮（撤销/重做按钮右侧）；
• 交互面板升级入口：第 21 章交互面板顶部有「🧩 打开蓝图 →」按钮，一键跳转。

工作区是可拖拽浮动窗口（六大铁律 #2）：标题栏按住拖动位置、⤢ 最大化/还原、✕ 或 Esc 关闭。标题栏右侧有 ▶ 运行 / ■ 停止 按钮随时试跑。

窗口内嵌的就是蓝图编辑器本体——与 SDK 独立分发版（sdk/blueprint/blueprint-editor.html）同一个文件：在 DPE 内打开时自动连接真实场景；单独打开时内置模拟面板演示。

22.3 五步做出第一条蓝图

以「点击蜗壳 → 相机飞过去 → 弹提示」为例：

1. 放事件节点：左侧节点库「事件」分类找到 物体单击，拖到画布（或右键画布搜索「单击」）；
2. 放动作节点：同样方式拖出 相机飞行 和 标签提示 两个动作节点；
3. 连线：从「物体单击」右侧白色箭头（执行流端口）拖到「相机飞行」左侧箭头，再连到「标签提示」——箭头决定先做什么后做什么；
4. 填参数：点选节点，右侧属性面板选目标构件（下拉里就是当前场景的真实构件名）、填时长与提示文字；
5. 运行：点标题栏 ▶ 运行，切到演示模式点击该构件——节点闪绿、连线流光，动作真实生效。

💡 白色箭头 = 执行流（顺序），彩色圆点 = 数据流（把算出来的值喂给别的节点，如「随机数」喂给「延时」的秒数）。参数没连线时用面板里填的默认值，连了线则以连线取值优先。

22.4 五类节点速览（44 种）

进阶：右上角可切换代码视图（DSL），蓝图 ⇄ 代码双向无损转化；自由代码折叠保留。AI 助手面板可按自然语言意图生成蓝图（应用前有 diff 预览）。

22.5 真实场景联动与模式门控（重要）

• 自动注入真实场景：工作区打开时，当前工程的全部构件、材质预设、动画序列自动进入蓝图下拉——选到的就是真实对象；动作执行直接驱动真实场景（显隐/飞行/材质全部真实生效）。
• 编辑模式不触发：编辑模式下视口点击 = 选中对象（不打断制作），蓝图事件链不会触发（标题栏有 ⚠ 提示徽标）。要体验蓝图交互，切到演示 / 培训 / 考核 / 播放 / 预览模式后再点击。
• 调试通道不受限：工作区 ▶ 运行按钮、面板按钮、API 显式调用（blueprint.run）任何时候都可用——那是制作者的调试通道。

22.6 保存：蓝图随工程落盘

画布上每次增删节点/连线/改参数，蓝图 JSON 自动写回当前工程——「保存 / 另存为」时随 vtpack 一起落盘，重开工程完整还原。也可用「导入/导出」在工程间迁移蓝图（.json 文件）。

22.7 API 速查（blueprint.* 共 6 项能力）

// AI 助手 / MCP / 父页面 一句话驱动：
await sdk.call('blueprint.open', {});
await sdk.call('blueprint.run', {});
// 二维大屏联动：comm.emit('open-panel') 触发蓝图里的二维界面事件节点

全部能力已注册 registry（MCP 自动透传），蓝图 JSON 协议与 SDK 独立版完全一致，详见 sdk/blueprint/README.md。

23. 🚀 部署与运维

面向：企业 IT / 运维人员（把编辑器与播放器部署到服务器）与前端开发者（SDK / API / MCP 集成快速上手）。DPE 是纯前端静态系统——没有后端编译步骤，任何静态服务器指向源码目录即可运行。

21.1 环境要求

21.1.1 三类角色的配置基线

21.1.2 私有化部署（内网 / 离线）

内网环境开箱即用：三维渲染等全部运行库已本地化在 vendor/，无任何公网 CDN 依赖。交付采用「三包分离」架构，由 build_packages.sh 一键构建：

1. 解压源码包与资源包到同一目录（资源包内 assets/ 与源码包占位目录自动合并，路径引用不变）；
2. 静态服务器指向该目录（内网 nginx / IIS 均可，见 21.2）；
3. 验证：打开 index.html 标题正确、模块加载无报错、curl http://服务器/assets/lib/ToyCar.glb 返回 200；
4. 交付清单（md5 / sha256 / 大小）随包自动生成，校验无误即完成。

21.2 部署方式（三选一）

21.2.1 方式一：nginx 静态托管（推荐）

完整生产配置示例——含 gzip 压缩、glb/wasm MIME 类型、缓存策略（index.html 不缓存 + 静态资源长缓存）与 SPA 404 兜底：

server {
    listen 80;
    server_name your-domain.com;            # 或 _ （IP 直访）
    root /opt/dpe-editor;                # 源码包+资源包合并目录
    index index.html;
    charset utf-8;                          # 中文文件名防乱码

    gzip on;
    gzip_types text/html text/css application/javascript application/json model/gltf-binary application/wasm;
    gzip_comp_level 6;

    # ① 大模型/二进制：正确 MIME + 断点续传（Range）+ 1 天缓存
    location ~* \.(glb|gltf|bin|wasm|vtpack)$ {
        types { }
        default_type application/octet-stream;
        # glb 也可显式声明 model/gltf-binary；wasm 必须是 application/wasm
        add_header Accept-Ranges bytes;
        add_header Cache-Control 'public, max-age=86400';
    }

    # ② 指纹类静态资源：一周长缓存（升级靠 ?v= 破除，见 21.3）
    location ~* \.(js|css|png|jpg|webp|hdr|mp4)$ {
        add_header Cache-Control 'public, max-age=604800';
    }

    # ③ 入口页与 manifest：不缓存，保证发版即时生效
    location = /index.html  { add_header Cache-Control 'no-cache'; }
    location = /player.html { add_header Cache-Control 'no-cache'; }
    location = /manifest.json { add_header Cache-Control 'no-cache'; }

    # ④ SPA 兜底：刷新子路径不 404
    location / { try_files $uri $uri/ /index.html; }
}

21.2.2 方式二：Docker（docker-compose）

# docker-compose.yml —— nginx 静态托管 + 可选视频网关 + 可选 MCP 网关
services:
  web:                                  # ① 编辑器/播放器静态托管（必选）
    image: nginx:alpine
    ports: ["80:80"]
    volumes:
      - ./dpe-editor:/usr/share/nginx/html:ro   # 三包合并目录
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    restart: unless-stopped

  mediamtx:                             # ② 视频转码网关（可选：rtsp→HLS/WebRTC）
    image: bluenviron/mediamtx:latest
    ports: ["8888:8888", "8554:8554"]   # 8888=HLS  8554=rtsp 入流
    restart: unless-stopped
    # 用法：摄像头 rtsp 推到 8554 流，相机属性里填 http://网关IP:8888/xxx/index.m3u8

  mcp-gateway:                          # ③ MCP 网关（可选：大模型智能体接入）
    image: node:22-alpine
    working_dir: /app
    command: sh -c "npm install && node server.js"
    volumes: ["./modules/mcp-gateway:/app"]
    ports: ["8970:8970", "8971:8971"]   # 8970=MCP HTTP  8971=编辑器 WS
    restart: unless-stopped

# 启动：docker compose up -d
# 仅纯静态托管时，删掉 mediamtx / mcp-gateway 两个服务即可（服务器 2核4G 足够）

21.2.3 方式三：腾讯云 / 任意云主机（deploy_tencent.sh）

仓库自带一键部署脚本 deploy_tencent.sh（rsync 增量同步 + 版本原子切换 + 自动回滚）：

1. 编辑脚本顶部【连接配置】：服务器 IP、SSH 端口/用户（建议先 ssh-copy-id 配免密）；
2. ./deploy_tencent.sh —— 首次自动创建目录、rsync 增量上传（只传变化文件，后续更新秒级完成）、自动写入 nginx 站点配置并 reload；
3. 部署为 releases → current 原子切换，上一版自动保留；出问题执行 ./deploy_tencent.sh rollback 一键回滚。

访问入口：http://服务器IP/（编辑器）与 http://服务器IP/player.html（播放器）。也可整体上传腾讯云 COS 开启静态网站托管（方式三变体）。

21.2.4 上线检查单（公网必读）

21.3 升级维护

21.3.1 版本号与缓存破除

入口页对 JS/CSS 引用统一带 ?v=版本号 参数（如 ?v=7.5，当前共 10 处）。发版时只需更新版本号参数，浏览器即视为新 URL 强制拉取——配合 21.2.1 的「入口不缓存 + 静态长缓存」策略，用户零感知升级、老版本资源对已开学员仍可用。

21.3.2 三包增量更新

• 源码包（高频）：每次发版只替换源码包内容即可，解压覆盖 current 目录（或重跑 ./deploy_tencent.sh，rsync 只传差异文件）；
• 资源包（低频）：仅模型库扩充时更新——合并解压到同一目录，长缓存一周内新旧课件均不受影响；
• SDK 包：随源码包同版本交付给集成方，接口只增不删（能力 manifest since 标记 + manifestDiff 差集可查新增）。

21.4 开发者上手（SDK / API / MCP 快速通道）

21.4.1 五分钟集成（DPE SDK）

v7.2 起 SDK 双模式：direct 直嵌（容器内直接渲染，API 直调零序列化，高频调用比 iframe 快 15~27 倍）+ iframe 兼容（跨域 / 完整编辑器能力），auto 模式自动协商。完整文档见 docs/sdk.md，360 项能力参数表见 api-reference.html。

<div id="viewer"></div>
<script src="/sdk/cimpro3d-sdk.js"></script>
<script>
  // 一个容器 + 一行初始化（不传 project 时加载内置示例课件）
  const viewer = await CIMPro3D.create('viewer', { /* project: { vtpack: '/xx.vtpack' } */ });
  viewer.explode.set(1);                        // 💥 爆炸图
  viewer.steps.play({ speed: 1.5 });            // ▶ 播放课件
  viewer.on('step.change', ev => console.log(ev.partName));  // 事件订阅
  // 跨域/需要完整编辑器：mode:'iframe' + src:'https://editor-host/?api=2'，其余代码一字不改
</script>

UMD / ESM 双格式 + TypeScript 类型定义（sdk/cimpro3d-sdk.d.ts），SDK 仅 6KB(gzip) 且自带隔离三维运行时不污染宿主；可运行示例：sdk/demo.html（direct）/ sdk/demo-iframe.html（iframe）/ sdk/test-host.html（最简骨架）。iframe 嵌入基础 API（cimpro3d-api.js 桥）见第 19 章。

21.4.2 DPE API 示例中心（api-playground.html）

不想读文档？打开 api-playground.html 交互式把玩全部 360 项能力（37 域分组）：

• 浏览能力：按域折叠分组 + 关键字搜索，含参数 schema / 版本 / since 标记；
• 自动表单：每个能力按 inputSchema 自动生成参数表单（枚举变下拉、必填标红），不用手拼 JSON；
• 一键运行：点运行即在下方法入三维场景实时看效果，结果 JSON 直接可复制；
• 事件日志：右侧滚动日志实时打印 prop.changed / step.change 等全部事件，调试联动的利器；
• 示例脚本：10 个一键示例（爆炸图巡检、相机飞行、标签批量创建等）开箱即改。

21.4.3 MCP 接入（大模型智能体）

把编辑器全部能力开放给 WorkBuddy / Claude / DeepSeek 等大模型智能体，走「网关透传」架构（完整部署文档 docs/mcp.md）：

# ① 启动网关（Node ≥ 18）
cd modules/mcp-gateway && npm install && node server.js   # HTTP 8970 / WS 8971

# ② 浏览器打开编辑器即自动连网关（右上角圆点：绿=已连）
http://your-host:8960/?mcp=ws://your-host:8971

# ③ 验证
curl http://your-host:8970/health      # {"ok":true,"sessions":1,"tools":170,...}

网关是纯透传层：tools/list 动态汇总各编辑器会话上报的能力清单（inputSchema 原样透传），编辑器侧新增能力网关零改动生效；生产建议 nohup / systemd / pm2 托管。Docker 方式见 21.2.2。

21.4.4 常见部署问题 FAQ

📝 更新记录（统一入口）

本手册为唯一文档入口：操作指南 + API 文档（见 🔌 DPE API）+ 更新记录。

24. ⌨ 快捷键速查表

25. ❓ 常见问题 FAQ